<P>
<H1>JettyPlus://</H1>

<h2> What it is and how to run it</h2>

The purpose of this project is to enrich Jetty by
selectively incorporating useful J2EE and non-J2EE features. The result is
JettyPlus, an environment offering additional facilities to
core web and servlet services, but which does not entail a full-blown 
application server (such as <A HREF="/jetty/jboss/index.html">JettyJBoss</A> and <A HREF="/jetty/jonas/index.html">JettyJOnAS</A>).
<P>
The feature set currently contains:


<ul>
  <li> <A HREF="http://java.sun.com/j2ee/transactions.html">Java
  Transaction API (JTA)</A> and Resource references, eg <A HREF="http://java.sun.com/j2se/1.4.1/docs/api/javax/sql/package-summary.html">DataSources</A> <font color=red><i>Updated</i></font>
  <li> <A HREF="http://java.sun.com/products/jndi/">Java Naming and Directory Interface API (JNDI)</A>
  <li> <A HREF="http://jakarta.apache.org/log4j/docs/">Log4J</A>  
  <li> <A HREF="http://java.sun.com/products/jaas/">Java Authentication and Authorization Service (JAAS)</A>
  <li> <A HREF="http://java.sun.com/products/javamail/">Java Mail</A>&nbsp; <font color=red><i>New</i></font>
  <li><A HREF="http://java.sun.com/products/JavaManagement/">JMX</a><font color=red><i>New</i></font>
</ul> 

<h3>How to run it</h3>
To use JettyPlus, you must:
<ul>
  <li> Configure the <code>org.mortbay.jetty.plus.Server</code>
  class in your xml configuration file rather than the standard
  <code>org.mortbay.jetty.Server</code> class, eg:
<BR>
  <code><pre>  &lt;Configure class="org.mortbay.jetty.plus.Server"&gt;</code></pre>
  </li>

  <li> Reference this class on the runline:
<BR>
  <code><pre>   java -Djetty.server=org.mortbay.jetty.plus.Server -Dlog4j.configuration=log4j.xml -jar start.jar config.xml
  </pre></code>
If you prefer, instead of specifying the class on the runline,
you can edit the <code>start.config</code> file inside
<code>start.jar</code> and change the line:
  <code><pre>
             # The main class to run
             org.mortbay.jetty.Server.class  

             to
 
             org.mortbay.jetty.plus.Server.class
  </pre></code>
  </li>
</ul>

<h3>How to run it with JMX</h3>
As with standard Jetty, you must use an mlet boot file to configure your JettyPlus servers and usually also a JMX http adaptor. An example can be found in <code><b>extra/etc/jettyplus.mlet</b></code>.  
<P>
To run with JMX do:
<BR>
java -Dstart.class=org.mortbay.util.jmx.Main -Dserver.class=org.mortbay.jetty.plus.Server -Dlog4j.configuration=log4j.xml -jar start.jar extra/etc/jettyplus.mlet
<BR>

<h3>More details</h3>
<P>
JettyPlus consists of
<code><b>org.mortbay.jetty.plus.jar</b></code>, ancillary file
<code><b>org.mortbay.jetty.plus.resource.jar</b></code>, and
optionally <code><b>org.mortbay.jaas.jar</b></code> as well
as a number of libraries found in <code><b>extra/ext</b></code>. If you use the convenient
start.jar method of running Jetty (highly recommended), all necessary jar files will
automatically be placed on the JVM classpath for you. Otherwise,
you will need to place the following on the Java classpath in
addition to the usual Jetty jars:
<ul>
  <li>org.mortbay.jetty.plus.jar
  <li>org.mortbay.jetty.plus.resource.jar
  <li>org.mortbay.jetty.jaas.jar (if you want to use JAAS)
  <li>activation.jar
  <li>mail.jar
  <li>carol.jar 
  <li>commons-cli.jar
  <li>commons-logging.jar
  <li>hsqldb.jar (only for running the demo webapps)
  <li>jonas_timer.jar
  <li>jotm.jar
  <li>jotm_iiop_stubs.jar
  <li>jotm_jrmp_stubs.jar
  <li>jta-spec1_0_1.jar
  <li>jts1_0.jar
  <li>log4j.jar
  <li>objectweb-datasource.jar
  <li>ow_util_log_file.jar
  <li>ow_util_log_wrp_log4j.jar
  <li>p6spy.jar
  <li>xapool.jar
</ul>
<P>
The <code>extra/plus/README.TXT</code> file in the source distribution
contains more information on the JettyPlus package, including
instructions on how to run the JettyPlus demonstration webapps.
<P>
<h2>Features</H2>
<H3>Transactions and DataSources</H3>
Thanks to the integration of the <A HREF="http://www.objectweb.org/jotm/index.html">JOTM</A> and <A
HREF="http://xapool.experlog.com/">XAPool</A> packages
from <A HREF="http://www.objectweb.org">ObjectWeb</A>,
it is now possible to easily incorporate distributed transactional semantics in your
servlets and JSPs using
<code>javax.transaction.UserTransaction</code> objects. 

<P>
For example:  code to obtain, start and commit a UserTransaction
is as follows:

<code><pre>
    try
    {
      UserTransaction usertransaction =
                      (UserTransaction)context.lookup("java:comp/UserTransaction");
      <font color="silver">//do some stuff</font>
      usertransaction.begin();
      <font color="silver">//access some resources and make changes</font>
      usertransaction.commit();
    }
    catch (Exception e)
    {
      usertransaction.rollback();
    }
</code></pre>

<P>
JettyPlus also provides support for
<code>javax.sql.DataSource</code> and <code>javax.sql.XADataSource</code> objects referenced in web.xml
<code>&lt;resource-ref&gt;</code> and <code>&lt;resource-env-ref&gt;</code>
elements. 

To use DataSources in your webapp, you need to:

<ul>
 <li><B>Step 1:</B>  reference the DataSource in your <code>web.xml</code>
 descriptor. Eg.
<code><pre>
  &lt;resource-env-ref&gt;
    &lt;description&gt;
      DB Connection
    &lt;/description&gt;
    &lt;resource-env-ref-name&gt;
      jdbc/myDB
    &lt;/resource-env-ref-name&gt;
    &lt;resource-env-ref-type&gt;
      javax.sql.DataSource
    &lt;/resource-env-ref-type&gt;
  &lt;/resource-env-ref&gt;
</pre></code>
 </li>
 <li><B>Step 2:</B> set up the DataSource in your JettyPlus xml
 configuration file. Note that this is configured along with the
 transaction service Eg:
<code><pre>
  &lt;Call name="addService"&gt;
    &lt;Arg&gt;
      &lt;New class="org.mortbay.jetty.plus.JotmService"&gt;
        &lt;Set name="Name"&gt;TransactionMgr&lt;/Set&gt;
        <font color="blue"> &lt;!-- set up a pooled DataSource --&gt;</font>
         &lt;Call name="addPooledDataSource"&gt;
             &lt;Arg&gt;jdbc/myDB&lt;/Arg&gt;   <font color="blue"&lt;!-- client lookup jndi name of datasource  --&gt;</font>
             <font color="blue">&lt;!-- set up the datasource --&gt;</font>
             &lt;Arg&gt;
               <font color="blue">
               &lt;!-- Uncomment one of the following types of XADataSource        --&gt;
               &lt;!-- according to your type of database:                         --&gt;
               &lt;!-- New class="org.enhydra.jdbc.sybase.SybaseXADataSource"      --&gt;
               &lt;!-- New class="org.enhydra.jdbc.informix.InformixXADataSource"  --&gt;
               &lt;!-- New class="org.enhydra.jdbc.oracle.OracleXADataSource"      --&gt;
               </font>
               &lt;New class="org.enhydra.jdbc.standard.StandardXADataSource"&gt;
                 &lt;Set name="DriverName"&gt;org.hsqldb.jdbcDriver&lt;/Set&gt;
                 &lt;Set name="Url"&gt;jdbc:hsqldb:extra/etc/tmtest&lt;/Set&gt;
                 &lt;Set name="User"&gt;sa&lt;/Set&gt;
                 &lt;Set name="Password"&gt;&lt;/Set&gt;
                 <font color="blue">
                 &lt;!-- Uncomment to setup isolation level as required            --&gt;
                 </font>
                 &lt;!--
                 &lt;Set name="TransactionIsolation"&gt;&lt;Get class="java.sql.Connection" name="TRANSACTION_SERIALIZABLE"/&gt;&lt;/Set&gt; 
                 --&gt;
               &lt;/New&gt;
             &lt;/Arg&gt;
             <font color="blue">&lt;!-- set up a pool for the datasource --&gt;</font>
             &lt;Arg&gt;
               &lt;New class="org.enhydra.jdbc.pool.StandardXAPoolDataSource"&gt;
                 &lt;Arg type="Integer"&gt;4&lt;/Arg&gt;          <font color="blue">&lt;!-- initial size of pool --&gt;</font>     
                 &lt;Set name="MinSize"&gt;4&lt;/Set&gt;                
                 &lt;Set name="MaxSize"&gt;15&lt;/Set&gt; 
                 <font color="blue">&lt;!-- Uncomment to setup other pool params as required          --&gt;</font>
                 &lt;!--
                 &lt;Set name="SleepTime"&gt;10&lt;/Set&gt;
                 &lt;Set name="LifeTime"&gt;10&lt;/Set&gt;
                 &lt;Set name="DeadLockMaxWait"&gt;10&lt;/Set&gt;
                 &lt;Set name="DeadLockRetryWait"&gt;10&lt;/Set&gt;
                 &lt;Set name="LoginTimeout"&gt;10&lt;/Set&gt;
                 &lt;Set name="Debug" type="boolean"&gt;true&lt;/Set&gt;
                 --&gt;
               &lt;/New&gt;
             &lt;/Arg&gt;               
        &lt;/Call&gt;

        Note: if your JDBC driver does connection pooling for you, then instead of 
        configuring both a <code>StandardXADataSource</code> and a <code>StandardXAPoolDataSource</code>, 
        you can just configure the <code>StandardXADataSource</code> instead: 


        <font color="blue">&lt;!-- set up a DataSource where the driver does the pooling                 --&gt;</font>
        &lt;Call name="addDataSource"&gt;
             &lt;Arg&gt;jdbc/otherDB&lt;/Arg&gt;    <font color="blue">&lt;!-- client lookup jndi name of datasource  --&gt;</font>
             &lt;Arg&gt;
               &lt;New class="org.enhydra.jdbc.standard.StandardXADataSource"&gt;
                 &lt;Set name="DriverName"&gt;com.mysql.jdbc.Driver&lt;/Set&gt;
                 &lt;Set name="Url"&gt;jdbc:mysql://localhost:3306/oln &lt;/Set&gt;
                 &lt;Set name="User"&gt;&lt;/Set&gt;
                 &lt;Set name="Password"&gt;&lt;/Set&gt;
               &lt;/New&gt;
             &lt;/Arg&gt;
        &lt;/Call&gt;
 
     &lt;/New&gt;
   &lt;/Arg&gt;
  &lt;/Call&gt;
</pre></code>
</li>

<li><B>Step 3:</B>  access it in your code. Eg:
<code><pre>
  DataSource datasource =
  (DataSource)context.lookup("java:comp/env/jdbc/myDB");
  Connection connection = datasource.getConnection();
</code></pre>
</li>

</ul>




<H3>Mail Service </H3>

A mail service is provided with JettyPlus. This means that you can send email programmatically from servlets, JSPs etc.
<P>
To use the mail service, you need to:
<P>
<ul>
 <li><B>Step 1:</B>  reference the Mail Service in your <code>web.xml</code>
 descriptor as a resource. Eg.
<code><pre>
  &lt;resource-env-ref&gt;
    &lt;description&gt;
      Mail Service
    &lt;/description&gt;
    &lt;resource-env-ref-name&gt;
      mail/Session <font color=silver>&lt;!-- must be same as JNDI name in xml config file (see step 2) --&gt;</font>
    &lt;/resource-env-ref-name&gt;
    &lt;resource-env-ref-type&gt;
      javax.mail.Session
    &lt;/resource-env-ref-type&gt;
  &lt;/resource-env-ref&gt;
</pre></code>
 </li>
 <li><B>Step 2:</B> set up the Mail Service in your JettyPlus xml
 configuration file. Eg:
<code><pre>
  &lt;Call name="addService"&gt;
    &lt;Arg&gt;
      &lt;New class="org.mortbay.jetty.plus.MailService"&gt;
        &lt;Set name="Name"&gt;MailService&lt;/Set&gt;
        &lt;Set name="JNDI"&gt;mail/Session&lt;/Set&gt;
        <font color="silver">&lt;!-- set up the id of the smtp user                 --&gt;</font>
        &lt;Set name="User"&gt;XXX&lt;/Set&gt;
        <font color="silver">&lt;!-- set up the password of the smtp user           --&gt;</font>
        &lt;Set name="Password"&gt;XXX&lt;/Set&gt;
        <font color="silver"> &lt;!-- set up the hostname/ip addr of the smtp server --&gt;</font>
        &lt;Put name="mail.smtp.host"&gt;XXX&lt;/Put&gt;  
        <font color="silver"> &lt;!-- setup any javax.mail.smtp provider variables   --&gt;</font>
        &lt;Put name="mail.pop3.user"&gt;zzz&lt;/Put&gt;
        &lt;Put name="mail.pop3.host"&gt;vvv&lt;/Put&gt;
        &lt;Put name="mail.from"&gt;me@me&lt;/Put&gt;
        &lt;Put name="mail.debug"&gt;false&lt;/Put&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/Call&gt;

<li><B>Step 3:</B>  access it in your code. Eg:
<code><pre>
  javax.mail.Session session =
  (javax.mail.Session)context.lookup("java:comp/env/mail/Session");
  Message msg = new MimeMessage(session);
  msg.setFrom(new InternetAddress("me@me.com"));
  msg.addRecipient(new InternetAddress("you@you.com"));
  msg.setContent("Hi");
  Transport.send(msg);
</code></pre>
</li>

</ul>



<H3>JNDI </H3>
JettyPlus supports JNDI, including ENC lookups of &lt;env-entry&gt; tags in the
web.xml descriptor. All you need to do to effect JNDI env lookups in your code is to:

 <ul>
 <li><B>Step 1:</B>  enter some env entries in your webapp
 web.xml file, eg:
<code><pre>
  &lt;env-entry&gt;
    &lt;env-entry-name&gt;
       someEnv
    &lt;/env-entry-name&gt;
    &lt;env-entry-value&gt;
       A long time ago in a galaxy far far away 
    &lt;/env-entry-value&gt;
    &lt;env-entry-type&gt;
       java.lang.String
    &lt;/env-entry-type&gt;
  &lt;/env-entry&gt;
</code></pre>
</li>

<li><B>Step 2:</B>  obtain a javax.naming.InitialContext object and call the lookup
method, eg:
<code><pre>
 InitialContext context = new InitialContext();
 String starwars = (String)context.lookup("java:comp/env/someEnv");
</code></pre>
</li>
</ul>

<font color=red><i>New:</i></font>&nbsp; JettyPlus JNDI service is now lenient on leading and trailing <code>"/"</code> elements of JNDI names. This avoids a lot of errors caused by mis-typings. For example, the following are all now equivalent:

<blockquote>
<code>
<pre>
java:comp/env/mything (strictly the correct form according to the spec)
java:/comp/env/mything
java:/comp/env/mything/
</pre>
</code>
</blockquote>
<P>


<H3> Log4J </H3>
The JettyPlus package provides a Jetty <code>org.mortbay.util.LogSink</code> to
enable Jetty log messages to appear in Log4J style logs. The
<code>org.mortbay.jetty.plus.resource.jar</code> file contains a
<code>log4j.xml</code> configuration file which may be modified
as needed.
<P>
To use Log4J:
<ul>
  <li><b>Step 1:</b>  configure the LogSink in your Jetty xml
  configuration file, eg:
<code><pre>
  &lt;Call name="instance" class="org.mortbay.util.Log"&gt;
    &lt;Call name="disableLog"/&gt;
    &lt;Call name="add"&gt;
      &lt;Arg&gt;
        &lt;New class="org.mortbay.util.log4j.Log4jSink"&gt;
          &lt;Call name="start"/&gt;
        &lt;/New&gt;
      &lt;/Arg&gt;
    &lt;/Call&gt;
  &lt;/Call&gt;
</pre></code>
</li>

<li><b>Step 2:</b>  enable it on the command line:
<code><pre>
  java -Dlog4j.configuration=log4j.xml -jar start.jar config.xml
</pre></code>
</ul>







<H3>JAAS</H3>
JAAS provides a pluggable framework for authenticating and
authorising users. JettyPlus JAAS integrates this with the declarative
security model of the Java Servlet Specification.
<P>
The Jetty JAAS classes are <emph>not</emph> included in the main
JettyPlus jar (<code>org.mortbay.jetty.plus.jar</code>). Instead, it is built
as <code>org.mortbay.jaas.jar</code> to enable it to be used
either with standard Jetty, or with JettyPlus.
<P>
As JAAS is a pluggable framework, the Jetty JAAS integration
aims to dictate as little as possible whilst providing
a sufficiently flexible infrastructure to allow users to drop in
their own custom LoginModules. An example LoginModule (<code>org.mortbay.jaas.spi.JDBCLoginModule</code>),
interacting with a database to store user names, passwords and
roles, is included with the release to illustrate what to
implement.
<P>
Some important classes are:

<h4>org.mortbay.jaas.JAASUserRealm</h4>
This bridges Jetty's realm concept to JAAS. This class must be
configured as the realm for your webapp.


<h4>org.mortbay.jaas.JAASPrincipal</h4>
Implements the java.security.Principal interface. This class is
used by the sample JDBCLoginModule, but the Jetty JAAS infrastructure
is Principal agnostic, meaning you can use your own
implementation of this class for your LoginModules if you wish.

<h4>org.mortbay.jaas.JAASRole</h4>
This is a Principal that represents a role possessed by a
user.

<h4>org.mortbay.jaas.JAASGroup</h4>
An implementation of the java.security.acl.Group interface. It is
used only by the sample JDBCLoginModule to group all roles
possessed by a user under a single Principal called "roles".

<h4>org.mortbay.jaas.spi.JDBCLoginModule</h4>
An implementation of a LoginModule that uses a database to store
user names, passwords and roles. All database-related information
is configurable, including:
<ul>
 <li>the names and columns of the user table and role table
 <li>the database connection driver, URL, username and password.
</ul>


<P>

To use JAAS:
<ul>
  <li><b>Step 1:</b>  Configure the realm for your webapp
  context in the Jetty xml configuration file:
  <code><pre>
    &lt;Call name="addWebApplication"&gt;
    &lt;Arg&gt;/jaas/*&lt;/Arg&gt;
    &lt;Arg&gt;&lt;SystemProperty name="jetty.home"/&gt;/extra/plus/demo/webapps/jaas&lt;/Arg&gt;

    &lt;Set name="Realm"&gt;
        &lt;New class="org.mortbay.jaas.JAASUserRealm"&gt;
          &lt;Set name="Name"&gt;Test JAAS Realm&lt;/Set&gt;
          &lt;Set name="LoginModuleName"&gt;jdbc&lt;/Set&gt;
          &lt;Set name="RoleCheckPolicy"&gt;
            &lt;New class="org.mortbay.jaas.StrictRoleCheckPolicy"/&gt;
          &lt;/Set&gt;
          &lt;Set name="CallbackHandler"&gt;
            &lt;New class="org.mortbay.jaas.callback.DefaultCallbackHandler"/&gt;
          &lt;/Set&gt;
        &lt;/New&gt;
    &lt;/Set&gt;
  &lt;/Call&gt;
  </pre></code>
  Note that it is only actually necessary to specify the
        <code>RoleCheckPolicy</code> or
        <code>CallbackHandler</code> if you have provided custom
        implementations of them.
 </li>
<BR>
 <li><b>Step 2:</b>  Configure some security constraints and a
        login method in your
        <code>web.xml</code> file, eg:
<code><pre>  
  &lt;security-constraint&gt;
    &lt;web-resource-collection&gt;
      &lt;web-resource-name&gt;JAAS Role&lt;/web-resource-name&gt;
      &lt;url-pattern&gt;/doit/*&lt;/url-pattern&gt;
    &lt;/web-resource-collection&gt;
    &lt;auth-constraint&gt;
      &lt;role-name&gt;roleA&lt;/role-name&gt;
    &lt;/auth-constraint&gt;
  &lt;/security-constraint&gt;

  &lt;login-config&gt;
    &lt;auth-method&gt;BASIC&lt;/auth-method&gt;
    &lt;realm-name&gt;Jetty Demo Realm&lt;/realm-name&gt;
  &lt;/login-config&gt;
</pre></code>
 </li>

 <li><b>Step 3:</b>  Create a login module configuration
  file. This one is from the Jetty JAAS demo (in <code>extra/etc/login.conf</code>):
  <code><pre>
      // sample login config file for the Jetty JDBCLoginModule
      // if you change the database and need to specify a password, set the property dbPassword
      jdbc {
      org.mortbay.jaas.spi.JDBCLoginModule required
      debug="true"
      dbUrl="jdbc:hsqldb:."
      dbUserName="sa"
      dbDriver="org.hsqldb.jdbcDriver"
      userTable="myusers"
      userField="myuser"
      credentialField="mypassword"
      userRoleTable="myuserroles"
      userRoleUserField="myuser"
      userRoleRoleField="myrole";
      };
  </pre></code> 
   Note that the name of the module ("jdbc") must be the same as
  that specified as the <code>LoginModuleName</code> in the Jetty
  xml config file in Step 1.
 </li>
<BR>
  <li><b>Step 4:</b>  Specify the location of the login
  configuration file on the Jetty run line by setting the
  <code>java.security.auth.login.config</code> property:
  <code><pre>
    -Djava.security.auth.login.config=mylogin.conf
  </pre></code>
 </li>
</ul>

<P>
The above describes how to use the Jetty JAAS integration to
authenticate web users and authorize them against webapp security
constraints. It can also be used for authorization with a Java
security manager and permission policy file. For information on
how to accomplish this, build and run the JAAS demo in <code>extra/plus</code>
as instructed in the README.TXT file in the source distribution.
